BTranslator

Derived from: BArchivable

Declared in: be/translation/Translator.h

Library: libtranslation.so

Summary

BTranslator is an abstract superclass that you subclass to define your own proprietary translator objects, one translator per BTranslator subclass. You add instances of your BTranslator subclasses to a BTranslatorRoster through BTranslatorRoster::AddTranslator(). BTranslator objects that your app creates and adds to the Roster are not visible to other applications.

Note that the BTranslator destructor is protected; you never delete a BTranslator from outside the class. Insead, you Release() it. See Acquire() for details.

The primary BTranslator functions are similar to the functions and data that a translator add-on supplies. Most of the BTranslator functions take you to the Translator Add-ons descriptions.

Constructor and Destructor

BTranslator()

	BTranslator()

The constructor must create and return a new instance of your BTranslator subclass. Note that the constructor doesn't Acquire() the object it returns.

~BTranslator()

	~BTranslator()

Note that the destructor is protected; you can only delete a BTranslator object from within the implementation of the subclass. From outside the class, you call Release().

Member Functions

Acquire() , Release() , ReferenceCount()

	BTranslator *Acquire(void) BTranslator *Release(void) int32 ReferenceCount(void) Debugging use only!

Acquire() and Release() increment and decrement the object's reference count. The count starts at 1 (i.e .the object is implicitly acquired when it's created); if the count falls to 0, the object is deleted.

When you add a BTranslator to a BTranslatorRoster, the BTranslator is automatically Acquire()'d. When the BTranslatorRoster is deleted, its BTranslators are Release()'d. Thus, when you instantiate a BTranslator and add it to a BTranslatorRoster, you and the Roster maintain joint ownership of the object. To give up ownership (such that the BTranslatorRoster will destroy the object when the Roster itself is destroyed), call Release() after adding the BTranslator to the Roster.

Acquire() and Release() both return a pointer to the BTranslator that was just acquired or released. If Release() caused the object to be deleted, it retruns NULL.

ReferenceCount(), which returns the current reference count value, is meant for debugging purposes only. It is not thread-safe! Don't predicate your code on the value it returns.

ReferenceCount() see Acquire()

GetConfigurationMessage()

	virtual status_t GetConfigurationMessage(BMessage *ioExtension)

Optional

Hook function that asks the object to write its current state into the BMessage argument. See GetConfigMessage() [Translator Add-ons] for details.

Identify()

	virtual status_t Identify(BPositionIO *inSource,       const translation_format *inFormat,       BMessage *ioExtension,       translator_info *outInfo,       uint32 outType) = 0

Required

Hook function called by the Translator Roster to ask the BTranslator if it knows how to convert inSource into the type described by outType. See Identify() [Translator Add-ons] for details.

InputFormats() , OutputFormats()

	virtual const translation_format *InputFormats(int32 *count) const virtual const translation_format *OutputFormats(int32 *count) const

Optional

These functions should be implemented to return arrays of translation_format structures that describe the formats that this object supports. If the functions aren't implemented, the object's Identify() function will be called each time an application requests a translation. Both functions should set count to the number of elements in the format array.

Unlike the analogous translator add-on format arrays, the arrays returned by these functions don't have to be terminated by an empty translation_format structure.

MakeConfigurationView()

	virtual status_t MakeConfigurationView(BMessage *ioExtension,       BView **outView,       BRect *outExtent)

Optional

Hook function that lets the BTranslator supply a configuration view. See MakeConfig() [Translator Add-ons] for details.

OutputFormats() see InputFormats()

Translate()

	virtual status_t Translate(BPositionIO *inSource,       const translator_info *inInfo,       BMessage *ioExtension,       uint32 outType,       BPositionIO *outDestination) = 0

Required

Hook function that asks the BTranslator to translate data from inSource to format outType, writing the output to outDestination. See Translate() [Translator Add-ons] for details.

TranslatorInfo() , TranslatorName() , TranslatorVersion()

	virtual const char *TranslatorInfo(void) const = 0 virtual const char *TranslatorName(void) const = 0 virtual int32 TranslatorVersion(void) const = 0

Required

TranslatorInfo() returns a pointer to the translator's long name, e.g. "aiff translator by the Pie Man (pie@the.man)".

TranslatorName() returns a pointer to the translator's short name, e.g. "aiff translator". The short name should be appropriate for display in a menu.

TranslatorVersion() gives an "MM.mm" version number for the translator. For example, a TranslatorVersion() of 314 is interpreted as version 3.14.